Welcome to the 41th post in the
$R^4 series. Just
as the
previous
post illustrated
r2u use to empower
interactive
Google
Colab sessions, today we want to look at continuous integration via
GitHub Actions.
Actions are very powerful, yet also intimidating and complex. How
does one know what to run? How does ensure requirements are installed?
What does these other actions do?
Here we offer a
much simpler yet
fully automatic
solution. It takes advantage of the fact that
r2u integrates
fully and
automatically with the system, here
apt
, without us having to worry about the setup. One way to
make this very easy is the use of the
Rocker containers for
r2u. They already include
the few lines of simple (and scriptable) setup, and have
bspm setup so that R
commands to install packages dispatch to
apt
and will bring
all required dependencies automatically and easily.
With that the required yaml file for an action can be as simple as
this:
name: r2u
on:
push:
pull_request:
release:
jobs:
ci:
runs-on: ubuntu-latest
container:
image: rocker/r2u:latest
steps:
- uses: actions/checkout@v3
- name: SessionInfo
run: R -q -e 'sessionInfo()'
#- name: System Dependencies
# # can be used to install e.g. cmake or other build dependencies
# run: apt update -qq && apt install --yes --no-install-recommends cmake git
- name: Package Dependencies
run: R -q -e 'remotes::install_deps(".", dependencies=TRUE)'
- name: Build Package
run: R CMD build --no-build-vignettes --no-manual .
- name: Check Package
run: R CMD check --no-vignettes --no-manual $(ls -1tr *.tar.gz tail -1)
There are only a few key components here.
First, we have the
on
block where for simplicity we
select pushes, pull requests and releases. One could reduce this to just
pushes by removing or commenting out the next two lines. Many further
refinements are possible and documented but not reqired.
Second, the
jobs
section and its sole field
ci
saythat we are running this CI on Ubuntu in its latest
release. Importantly we then also select the
rocker container for
r2 meaning that we
explicitly select running in this container (which happens to be an
extension and refinement of
ubuntu-latest
). The
latest
tag points to the most recent LTS release, currently
jammy aka 22.04. This choice also means that our runs are
limited to Ubuntu and exclude macOS and Windows. That is a choice: not
every CI task needs to burn extra (and more expensive) cpu cycles on the
alternative OS, yet those can always be added via other yaml files
possibly conditioned on fewer runs (say: only pull requests) if
needed.
Third, we have the basic sequence of
steps
. We check out
the repo this file is part of (very standard). After that we ask
R
show the session info in case we need to troubleshoot.
(These two lines could be commented out.) Next we show a commented-out
segment we needed in another repo where we needed to add
cmake
and
git
as the package in question
required local compilation during build. Such a need is fairly rare, but
as shown can be be accomodated easily while taking advantage of the rich
development infrastructure provided by Ubuntu. But the step should be
optional for most R packages so it is commented out here. The next step
uses the
remotes package
to look at the DESCRIPTION file and install all dependencies which,
thanks to
r2u and
bspm, will use all Ubuntu
binaries making it both very fast, very easy, and generally failsafe.
Finally we do the two standard steps of
building the source
package and
checking it (while omitting vignettes and the (pdf)
manual as the container does not bother with a full texlive
installation this could be altered if desired in a derived
container).
And that s it! The startup cost is a few seconds to pull the
container, plus a few more seconds for dependencies and let us recall
that
e.g. the entire tidyverse installs all one hundred plus
packages in about twenty seconds as shown in earlier post. After that
the next cost is generally just what it takes to build and check your
package once all requirements are in.
To use such a file for continuous integration, we can install it in
the
.github/workflows/
directory of a repository. One
filename I have used is
.github/workflows/r2u.yaml
making
it clear what this does and how.
More information about
r2u is at its site, and we
answered some question in issues, and at stackoverflow. More questions
are always welcome!
If you like this or other open-source work I do, you can now
sponsor me at
GitHub.
This post by Dirk
Eddelbuettel originated on his Thinking inside the box
blog. Please report excessive re-aggregation in third-party for-profit
settings.